MQTT Integration

This section lists messages you can send to supOS through MQTT.

Topic Definition

• Topic /{auth token}/{endpoint id}/{endpoint name}/{method name}/{direction}
• Field Description

Field	Description	Remarks
auth token	UUID assigned by supOS under Access Management.	-
endpoint id	Custom ID of the accessing device, recommended to be the MAC address of the gateway.	-
endpoint name	Name of the accessing device as defined by supOS under Access Management.	-
direction	push: Request from cloud. push_reply: Response to cloud request. get: Gateway requests cloud. get_reply: Cloud responds to gateway. report: Actively send to cloud. retain: Actively send to cloud, requesting cloud to retain the message, mainly used for synchronization of configuration, setup information with cloud.	Different method names support different topic directions.

• Method Name List

Function	Method Name/Topic Direction	Description	Remarks
Device actively sends tag data	metatag/retain	Unidirectional upload, cloud does data persistence assurance	Required
Device actively sends real-time data	rtdvalue/report	Unidirectional upload	Required
Device actively sends cached resume data	cachevalue/report	Unidirectional upload	Required
Device actively sends events	rtdevent/report	Unidirectional upload	Optional
Device actively sends requests	rtdevent/get	Event request	Optional, event support extensible, currently supports event: 1-System time synchronization
	rtdevent/get_reply	Event response, no response is an exception, continuous no response can be considered as cloud exception
Cloud actively refreshes tag data	metatag/push	Metadata active refresh request, requesting device to actively send a full set of tag data once	Mandatory, cloud will only actively send refresh request when necessary
	metatag/push_reply	Metadata active refresh response, continuous no response can be considered as device exception
Cloud actively refreshes real-time data	rtdvalue/push	Real-time data active refresh request, requesting device to actively send a full set of real-time data once	Mandatory, cloud will only actively send refresh request when necessary
	rtdvalue/push_reply		Real-time data refresh response, continuous no response can be considered as device exception
Cloud actively sends event notifications	rtdevent/push	Event notification request	Optional
	rtdevent/push_reply	Event notification response, continuous no response can be considered as device exception
Cloud actively sends write notifications	rtdnotify/push	Cloud write notification	Optional, collectors supporting write features need to subscribe
	rtdnotify/push_reply	Gateway write response

info

Examples in this section used the following information in the topic:

• auth token: 86efdf12-4f54-4691-b833-09cbaa2d50a4
• endpoint id: dev1234
• endpoint name: test

Metatag

Device Actively Refreshes Tag

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/metatag/retain

MQTT Parameter

QoS = 0，Retain = 1

Message

MetaTagSequence

Remarks

The device will actively send tag meta data to supOS once turned on.

Cloud Requires Refreshing Tag

Cloud Request

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/metatag/push

MQTT Parameter

QoS = 1，Retain = 0

Message

None

Remarks

Refresh request will be automatically triggered from cloud when service restarted.

Response

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/metatag/push_reply

MQTT Parameter

QoS = 1，Retain = 0

Message

MetaTagSequence

Real-time Data

Device Actively Sends Real-time Data

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdvalue/report

MQTT Parameter

QoS = 1，Retain = 0

Message

ValueSequence

Remarks

The device actively send real-time data after tag data sent.

Cloud Requires Refreshing Real-time Data

Cloud Request

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdvalue/push

MQTT Parameter

QoS = 1，Retain = 0

Message

None

Remarks

Refresh request will be automatically triggered from cloud when service restarted.

Response

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdvalue/push_reply

MQTT Parameter

QoS = 1，Retain = 0

Message

ValueSequence

History Data

Device Actively Resumes History Data

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/cachevalue/report

MQTT Parameter

QoS = 1，Retain = 0

Message

ValueSequence

Remarks

The device stores real-time data that failed to be sent and resumes to send the data again when network restored.

Custom Event

Device Actively Reports Event

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdevent/report

MQTT Parameter

QoS = 1，Retain = 0

Message

RtdEvent

Remarks

RtdEvent is reserved for devices to customize data report mechanism.

Device Requests Cloud Event

Device Request

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdevent/get

MQTT Parameter

QoS = 1，Retain = 0

Message

RtdEvent

Remarks

Device requests and cloud is required to response.

Response

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdevent/get_reply

MQTT Parameter

QoS = 1，Retain = 0

Message

RtdEvent

Remarks

Cloud response.

Cloud Event Notification

Cloud Request

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdevent/push

MQTT Parameter

QoS = 1，Retain = 0

Message

RtdEvent

Remarks

Cloud actively sends notifications to device according to business needs.

Response

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdevent/push_reply

MQTT Parameter

QoS = 1，Retain = 0

Message

RtdEvent

Remarks

Device reponses after processing the notified event.

System Embedded Event

System Time Synchronization

Device Request

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdevent/get

MQTT Parameter

QoS = 1，Retain = 0

Message

• RtdEvent
• topic = SyncTime
• payload = GatewayCoordinate

Remarks

Device actively sends request to cloud for time synchronization.

Response

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdevent/get_reply

MQTT Parameter

QoS = 1，Retain = 0

Message

• RtdEvent
• topic = SyncTime
• payload = ServerCoordinate

Remarks

Cloud responses to time synchronization request from device.

Cloud Sends Event Notification

Cloud Request

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdnotify/push

MQTT Parameter

QoS = 0，Retain = 1

Message

ValueSequence

Remarks

Cloud actively requests device to response.

Response

Topic

/86efdf12-4f54-4691-b833-09cbaa2d50a4/dev1234/test/rtdnotify/push_reply

MQTT Parameter

QoS = 1，Retain = 0

Message

None

Remarks

Device reponses to cloud.